home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / comm / term / ncomm30.lha / NComm / Doc / Script.doc < prev    next >
Text File  |  1993-09-29  |  31KB  |  966 lines
  1. The NComm V3.0 script language
  2. ==============================
  3.  
  4. A scriptfile is an ASCII textfile that consists of different commands,
  5. separated by  one or more  linefeeds.  Edit the  scriptfiles with your
  6. favourite  editor.  Only  one  command is  allowed per line, but blank
  7. lines are also OK. A line can consist of blanks before the command and
  8. between parameters.  Comments can be added by entering a semicolon.  A
  9. label is marked with a colon as its last character, e.g. "quit:".  The
  10. script  commands  are case independent,  but strings within quotes are
  11. not.
  12.  
  13. Scripts  are mainly used to automate logons, or to companion you while
  14. you  are  online.   Scripts  can also perform more advanced functions,
  15. like  grabbing  mail  and perhaps posting it on another board (or even
  16. printing it!).  You set the limits...
  17.  
  18. NComm  scripts  can be started from the menu or from the phonebook (at
  19. CONNECT).  You may also Shift-Select a script when starting NComm.
  20.  
  21. One example  script and  one  Host-Mode script have been included with
  22. the NComm package.  Take a look at them if you don't understand how to
  23. use the commands.
  24.  
  25. Important:   The  filenames  specified in a scriptfile are relative to
  26. the   current   directory,   NOT   the  default  upload  and  download
  27. directories!
  28.  
  29. Quick-Index (strings within brackets are optional)
  30. --------------------------------------------------
  31.  
  32. ASCSEND "filename"         : Send a file to the serial port
  33. AUTODOWN ON|OFF            : Turn Zmodem auto-download on or off
  34. AUTOUP ON|OFF              : Turn Zmodem auto-upload on or off
  35. AUTOXFER ON|OFF            : Turn G&R commands on or off
  36. BEEP                       : Make an audible/visible/screentofront beep
  37. BREAK                      : Send a break to the host machine
  38. CAPTURE "filename"         : Capture serial input to a file
  39. CD "directory"             : Change current directory for "CLI" commands
  40. CHAIN "filename"           : Start another script
  41. CLEARVARS                  : Clear all variables
  42. CLI "command"              : Execute external command
  43. CLRSTACK                   : Clear the RETURN stack
  44. CONFIG "filename"          : Load another configuration file
  45. CONVERSE "in" "out"        : Wait for input, send output
  46. DELAY seconds              : Wait for specified number of seconds
  47. DIAL "boardname"[,"next"]  : Dial one or more entries in phonebook
  48. DIAL# "number"[,"next"]    : Dial one or more telephone numbers
  49. DLWHEN                     : Delete last WHEN command
  50. DORX "filename"            : Execute an ARexx command/script
  51. DOWNLOAD "filename"[,P]    : Download file [with protocol P]
  52. DTENTHS tenthseconds       : Delay for specified number of tenthseconds
  53. DUMP ["filename"]          : Dump list of variables [to optional file]
  54. DWHEN "string"             : Delete WHEN checking for "string"
  55. DWHENS                     : Delete all WHEN statements
  56. ECHO ON|OFF                : Enable/disable INPUT/ASCSEND/MSGSEND cmd echo
  57. END                        : Stop execution of script
  58. GOSUB subroutine           : Call a subroutine
  59. GOTO label                 : Jump to a label
  60. HANGUP                     : Hang up the phone
  61. IF <exp> THEN <command>    : Execute command if expression is TRUE
  62. INPUT $variable "stopchar" : Put serial-port input in variable, until stopchar
  63. LOADKEYS "filename"        : Load a new set of macrokeys
  64. LOADPHONE "filename"       : Load a new phonebook
  65. MENUSELECT menu item sub   : Select an item/subitem from the menu
  66. MESSAGE "message"          : Display a message on the terminal
  67. MSGSEND "filename"         : Send a message to the serial port
  68. NCOMMTOFRONT               : Brings the NComm screen to front
  69. PADLINES ON|OFF            : Turn padding of blank lines off/on
  70. PALETTE                    : Open the palette requester
  71. PRINTER ON|OFF             : Turn the printer on or off
  72. QUIT                       : Exit NComm
  73. READVAR $variable          : Read a line from VARFILE into $variable
  74. REPEAT<->UNTIL <expression>: Perform a loop until expression is TRUE
  75. REDIAL ON|OFF              : Turn redial on or off
  76. REQUEST ON|OFF             : Turn system/NComm requesters on/off
  77. RESUME ON|OFF              : Turn Zmodem resume on or off
  78. RETURN                     : Returns from a sub-routine (see GOSUB)
  79. SEND "string"              : Send a string to the serial port
  80. SET $variable = "value"    : Assign value to $variable
  81. SIMPLEREQ "string"         : Display string in a simple requester
  82. STRPART out pos len in     : Places parts of the in string in the out string
  83. TIMEOUT seconds [command]  : Sets timeout to seconds [and command at timeout]
  84. UPLOAD "filename"[,P]      : Upload file [with protocol P]
  85. VARFILE "filename"|CLOSE   : Open file for input/close file (see READVAR)
  86. WAIT "string"              : Waits for string to be received (see TIMEOUT)
  87. WHILE <exp> DO...ENDWHILE  : Perform loop if expression is TRUE (check first)
  88. WHEN "string" command      : Execute command when string is received
  89. WRITE "filename" "string"  : Write string to file
  90.  
  91. Summary of Script commands
  92. --------------------------
  93.  
  94.         ASCSEND
  95. Starts ASCII text send of the filename given. Example:
  96.  
  97. ASCSEND "df1:text/msg"
  98.  
  99. The  TIMEOUT command also concerns ASCSEND.  If ASCSEND is halted by a
  100. ^S  and  no  ^Q  has  been  received within the timelimit specified by
  101. TIMEOUT,  the  script  will  go on with the next command.  XON will be
  102. turned on before ASCSEND.
  103.  
  104. ----------------------------------------------------------------------
  105.  
  106.         AUTODOWN
  107. Turns Zmodem auto-download ON or OFF.
  108.  
  109. Example:
  110.  
  111. AUTODOWN ON      ;Turns Zmodem auto-download on
  112. AUTODOWN OFF     ;Turns Zmodem auto-download off
  113.  
  114. ----------------------------------------------------------------------
  115.  
  116.         AUTOUP
  117. Turns Zmodem auto-upload ON or OFF.
  118.  
  119. Example:
  120.  
  121. AUTOUP ON      ;Turns Zmodem auto-upload on
  122. AUTOUP OFF     ;Turns Zmodem auto-upload off
  123.  
  124. ----------------------------------------------------------------------
  125.  
  126.         AUTOXFER
  127. Turns G&R commands ON or OFF.
  128.  
  129. Example:
  130.  
  131. AUTOXFER ON      ;Turns G&R commands on
  132. AUTOXFER OFF     ;Turns G&R commands off
  133.  
  134. ----------------------------------------------------------------------
  135.  
  136.         BEEP
  137. Will  cause  an audible 'beep' of the terminal and / or will flash the
  138. screen  and / or will bring the screen to front, depending on what you
  139. have  configured  in  the  SCREEN  menu.   Nothing is sent through the
  140. serial port.
  141.  
  142. ----------------------------------------------------------------------
  143.  
  144.         BREAK
  145. Sends a break to the host machine. Equivalent to SEND "\l".
  146.  
  147. ----------------------------------------------------------------------
  148.  
  149.         CAPTURE
  150. Toggles ASCII capture on/off. Examples:
  151.  
  152. CAPTURE "filename"
  153. Will  open the capture file and turn on capture.  It will be opened in
  154. 'append mode' if the file exists...
  155.  
  156. CAPTURE SUS
  157. Will suspend capture.  Capture can be turned on again with the command
  158. CAPTURE ON
  159.  
  160. CAPTURE OFF
  161. Will  turn  capture off and close the file.  The file cannot be opened
  162. again with the CAPTURE ON command.
  163.  
  164. ----------------------------------------------------------------------
  165.  
  166.         CD
  167. Problems  occur  when  the "CD" command is used with the CLI function.
  168. The  "CD"  command  has  therefore  been  made a special function.  It
  169. simply  changes  the directory that is to be used for commands started
  170. with the "CLI" function.
  171.  
  172. Example:
  173.  
  174. CD "RAM:"       ;Will change the current working directory to 'RAM:'
  175.  
  176. ----------------------------------------------------------------------
  177.  
  178.         CHAIN
  179. Will start a new script.  The control will never return to the calling
  180. script.   This  is  useful  when  you need extremely long scripts that
  181. won't fit in memory.
  182.  
  183. Example:
  184.  
  185. CHAIN "NComm:ReadNews.script"
  186.  
  187. Note:   Variables  will  not  be deleted when using the CHAIN command.
  188. Use the command CLEARVARS if you want to delete all variables.
  189.  
  190. ----------------------------------------------------------------------
  191.  
  192.     CLEARVARS
  193. This command deletes all variables.
  194.  
  195. ----------------------------------------------------------------------
  196.  
  197.         CLI
  198. Will  execute  a program or a command.  The output from these programs
  199. and  commands  will  occur  in the NComm window.  This command will be
  200. relative to the directory you were standing in when you started NComm.
  201.  
  202. Please  note;  Current  Directory can not be set with the CLI command,
  203. probably  due  to  problems with the Amiga operating system.  The "CD"
  204. function must therefore be used for this purpose.
  205.  
  206. Examples:
  207.  
  208. CLI "dir dh0:comms"
  209. CLI "type ram:foo.bar"
  210. CLI "pkax ram:grabfile.arc"
  211.  
  212. ----------------------------------------------------------------------
  213.  
  214.         CLRSTACK
  215. This  command  clears  the  RETURN  stack,  i.e.   it  forgets  active
  216. subroutine  calls (gosubs).  The command is handy at error situations,
  217. when  you  wish to "jump out" of the program and start over again, for
  218. example in conjunction with TIMEOUT or WHEN commands.
  219.  
  220. ----------------------------------------------------------------------
  221.  
  222.         CONFIG
  223. Will read a new configuration file.  Example:
  224.  
  225. CONFIG "NComm:MBBS.config"
  226.  
  227. ----------------------------------------------------------------------
  228.  
  229.         CONVERSE
  230. Will wait for a prompt from the host machine and answer it.
  231.  
  232. Examples:
  233.  
  234. CONVERSE "Enter your name:" "Name\n"   ;Waits for 'Enter your name:'
  235. CONVERSE "enter your password:" "\p\n" ;Sends phonebook password + CR
  236. CONVERSE "Command:" "G\n"              ;Sends 'G' and newline
  237.  
  238. ----------------------------------------------------------------------
  239.  
  240.         DELAY
  241. The  script  program  will take a break.  The program will function as
  242. normal.
  243.  
  244. Examples:
  245.  
  246. DELAY 5                 ;Wait 5 seconds
  247. DELAY UNTIL 12:00       ;Wait until 12 o'clock.
  248.  
  249. ----------------------------------------------------------------------
  250.  
  251.         DIAL
  252. Will  dial  one  or  more  phonenumbers.  Can also dial entries in the
  253. phonebook.   If  you  choose  to  dial  phonenumbers,  use the command
  254. 'DIAL#'.   The  numbers must be placed within quotation marks.  If you
  255. choose to dial more than one number, the numbers can be separated by a
  256. comma.
  257.  
  258. Examples:
  259.  
  260. DIAL# "454143"
  261. DIAL# "380949", "416588", "454143"
  262.  
  263. Named  entries  in  the  phonebook  can  be  dialled by specifying the
  264. boardname within quotation marks.  You only have to specify the number
  265. of  letters  required  to  separate  the  board  from the others.  The
  266. name is not case sensitive.
  267.  
  268. Examples:
  269.  
  270. DIAL "AmigaBBS"
  271. DIAL "rode", "Mike's", "media"
  272. DIAL "Rodeløkka (M)BBS"
  273.  
  274. ----------------------------------------------------------------------
  275.  
  276.         DLWHEN
  277. Deletes  the last defined WHEN command.  Repeated usage will succesive
  278. delete the "previous" WHEN command.  See:  WHEN.
  279.  
  280. ----------------------------------------------------------------------
  281.  
  282.     DORX
  283. This command executes an ARexx command/script.
  284.  
  285. Example: DORX "ncomm:test_rx.ncomm"
  286.  
  287. ----------------------------------------------------------------------
  288.  
  289.         DOWNLOAD
  290. Will download a file from the host machine.  The protocol specified in
  291. the  TRANSFER  menu will be used as long as nothing else is specified.
  292. If you want to specify another protocol, enter a comma and a letter.
  293. The filename is "dummy" when using Zmodem.
  294.  
  295. X == Xmodem, Y == Ymodem, B == Ymodem-B, G == Ymodem-G, Z == Zmodem,
  296. K == Kermit, E == External XPR (as defined in config file),
  297. I == Bimodem, P == BModem Plus, J == Jmodem, Q == QuickB,
  298. V == VMS, U == Uue-Ascii
  299.  
  300. Examples:
  301.  
  302. DOWNLOAD "df1:junk"             ;Will use the default protocol
  303. DOWNLOAD "df0:trash",X          ;Will always use Xmodem
  304.  
  305. ----------------------------------------------------------------------
  306.  
  307.         DTENTHS
  308. This  is  a much more precise delay command, but only use this command
  309. when  this  accuracy is needed, since it will lock up the system.  The
  310. DTENTHS parameter is the number of tenth seconds to wait.
  311.  
  312. Examples:
  313.  
  314. DTENTHS 2       ;Wait 0.2 seconds
  315. DTENTHS 16      ;Wait 1.6 seconds
  316.  
  317. ----------------------------------------------------------------------
  318.  
  319.         DUMP
  320. Command  for debugging a script.  It dumps a list of all variables and
  321. what  they contain, on screen.  If you specify a filename, output will
  322. be appended to the file instead, and will not be shown on screen.
  323.  
  324. Example: DUMP "t:debug_info"
  325.  
  326. ----------------------------------------------------------------------
  327.         DWHENS
  328. Deletes a specific WHEN command. It should be followed by the string
  329. that you used for activating the WHEN command.
  330.  
  331. Example:
  332.     WHEN "abc" GOTO abc
  333.         WHEN "bcd" GOTO bcd
  334.         [...]
  335.         DWHEN "abc" ;remove "abc" when checking
  336.  
  337. ----------------------------------------------------------------------
  338.  
  339.         DWHENS
  340. Will disable all previously used WHEN commands. See: WHEN.
  341.  
  342. ----------------------------------------------------------------------
  343.  
  344.         ECHO
  345. This  command defines if characters read by the INPUT command shall be
  346. echoed.   ECHO ON should be used when input is read from a user in the
  347. other  end. ECHO OFF should be used when input is read from a Bulletin
  348. Board  System, or when the user is not supposed to see what he writes.
  349.  
  350. ECHO  should  be  turned  ON  if the functions ASCSEND and MSGSEND are
  351. supposed  to  echo text locally.  The output from the CLI command will
  352. be sent to the serial port if ECHO has been turned on.
  353.  
  354. ----------------------------------------------------------------------
  355.  
  356.         END
  357. Will  stop  the  execution  of the script.  This command is especially
  358. useful in front of subroutines.
  359.  
  360. Example:
  361.  
  362. WHEN "Read>" GOSUB next
  363. WAIT "No more unread."
  364. END
  365.  
  366. Next: SEND "\n"
  367.       MESSAGE "(Skipping to next unread)\n"
  368.       RETURN
  369.  
  370. ----------------------------------------------------------------------
  371.  
  372.         GOSUB
  373. Will  call  a  named subroutine.  Useful when you want to use the same
  374. command  many  times  within  a  script, or in connection with WHEN or
  375. TIMEOUT.   The  subroutine  is ended with 'RETURN', and the control is
  376. passed to the line following the GOSUB afterwards.
  377.  
  378. Example:
  379.  
  380. GOSUB myRoutine
  381. END
  382.  
  383. MyRoutine: MESSAGE "Fooo\n"
  384.            BEEP
  385.            RETURN
  386.  
  387. ----------------------------------------------------------------------
  388.  
  389.         GOTO
  390. Ever heard of this? Will jump to a named place in the script.
  391.  
  392. Example:
  393.  
  394. GOTO quit
  395. ...
  396. quit: CAPTURE OFF
  397.       HANGUP
  398.       END
  399.  
  400. Numeric example that counts from 1 to 100:
  401.  
  402. SET $sum="0"
  403.  
  404. SUM: SET $sum = $sum+"1"#
  405.      MESSAGE "Number: "$sum"\n"
  406.      IF !$sum == "100" THEN GOTO SUM
  407.  
  408. NOTE:   Don't  use "LABEL:  GOTO LABEL" if you want an "endless" wait.
  409. This  will  steal  most  of  your machine's CPU.  Use the DELAY or WAIT
  410. commands instead.
  411.  
  412. ----------------------------------------------------------------------
  413.  
  414.         HANGUP
  415. Will send the hangup string to the modem (or lower DTR if you have
  416. selected DTR hangup).
  417.  
  418. ----------------------------------------------------------------------
  419.  
  420.         IF <expression> THEN <operation>
  421.  
  422. It  should be obvious what this command does.  A valid expression can
  423. be either a comparison of two strings or a check for a file.  The
  424. exclamation mark ('!') works as a boolean 'NOT' operator.
  425.  
  426. String comparisons are performed with the "==" operator, which tests for
  427. case independent equality, i.e.  "foo" == "FOO" is TRUE;
  428. !"bar" == "yum" is TRUE (because of the '!' (NOT) operator)
  429.  
  430. EXISTS  checks  if a file exists.  The following are examples on valid
  431. IF commands:
  432.  
  433. SELECTFALSE  opens  up  a "Yes / No" requester and is TRUE if the user
  434. selected "No".
  435.  
  436. RING checks for a (hardware) RING signal.
  437.  
  438. CARRIER checks for (hardware) CARRIER detect.
  439.  
  440.         IF $password == "abcdef" THEN MESSAGE "Access granted\n"
  441.         IF !$password == "xyz" THEN GOTO KillUser
  442.         IF EXISTS "NComm:host.config" THEN CONFIG "NComm:host.config"
  443.         IF !EXISTS $file THEN SEND "File not found!\n"
  444.  
  445.         IF !SELECTFALSE "Slow modem?" THEN SET $baud = "300"
  446.  
  447.         Loop: DELAY 1
  448.               IF RING THEN GOSUB Send_ATA
  449.               IF CARRIER THEN GOTO Connect
  450.               GOTO Loop
  451.  
  452. The whole command must be placed on a single line, including the 'THEN'
  453. part...
  454.  
  455. SEE ALSO: SET
  456.  
  457. ----------------------------------------------------------------------
  458.  
  459.         INPUT
  460. This  command  reads  input  from  the  serial port and places it in a
  461. variable  until  a  specific string has been received.  ^H (backspace)
  462. deletes  the  last  character,  ^U  deletes  the  whole  string.   The
  463. searchstring  will  not  be added to the variable.  Control characters
  464. will not be added.  Example:
  465.  
  466.         SEND "Enter your first name: "
  467.         INPUT $name "\r" ;Input will be placed in the variable 'name'
  468.                          ;until carriage return is received.
  469.  
  470. The  TIMEOUT  command  also  concerns  the INPUT command.  The timeout
  471. defines  how long INPUT shall wait for the terminating string ("\r" in
  472. the mentioned example).  Example:
  473.  
  474.         TIMEOUT 180 Goto BiBi
  475.         SEND "Enter a command: "
  476.         INPUT $cmd "\r"
  477.         ...
  478.  
  479. BiBi:   SEND "\n\nLooks like you fell asleep!!  Bye-bye!\n"
  480.         HANGUP
  481.         END
  482.  
  483. It is also possible to read a single character without having to
  484. wait for ENTER or other strings:
  485.  
  486.         INPUT $char ""
  487.  
  488. INPUT  can  both  be  used for reading input from a user in connection
  489. with  "Host  Mode",  or  grabbing pieces of text from a Bulletin Board
  490. System;
  491.  
  492.         WAIT "Bulletins have been updated: "
  493.         INPUT $bull " "
  494.  
  495. ----------------------------------------------------------------------
  496.  
  497.         LOADKEYS
  498. Will read a new macrokeys file.
  499.  
  500. Example:
  501.  
  502. LOADKEYS "NComm:dec.Keys"
  503.  
  504. ----------------------------------------------------------------------
  505.  
  506.         LOADPHONE
  507. Will read a new phonebook file.
  508.  
  509. Example:
  510.  
  511. LOADPHONE "NComm:dialdir.phone"
  512.  
  513. ----------------------------------------------------------------------
  514.  
  515.     MENUSELECT
  516. This command selects a function from the menu.
  517.  
  518. Example:
  519.     MENUSELECT SYSTEM 0     ;Open About Window
  520.         MENUSELECT TRANSFER 6 2 ;Selects KERMIT Change Directory
  521.  
  522. ----------------------------------------------------------------------
  523.  
  524.         MESSAGE
  525. Will  write  a  message  on  the  screen.  Nothing is sent through the
  526. serial port.  You may use all the conventions that are valid for
  527. macrokeys. Please refer to the NComm.doc.
  528.  
  529. Example:
  530.  
  531. MESSAGE "\fReading mail...\n"
  532. MESSAGE "Storing mail in file \"DF1:Mail.txt\"\n"
  533.  
  534. SET $var = 5
  535. MESSAGE "1"+$var-"2"#"\n"  ;The result will be 4 ((1+5)-2)
  536.  
  537. ----------------------------------------------------------------------
  538.  
  539.         MSGSEND
  540. Same  as the "message send" function in the TRANSFER menu, will upload
  541. a message.
  542.  
  543. Example:
  544.  
  545. MSGSEND "DF1:tekst/msg"
  546.  
  547.  
  548. ----------------------------------------------------------------------
  549.  
  550.         NCOMMTOFRONT
  551. Brings the current NComm screen to front.
  552.  
  553. Example:
  554.  
  555. NCOMMTOFRONT
  556.  
  557. ----------------------------------------------------------------------
  558.  
  559.         PADLINES
  560. Turns padding of blank lines ON or OFF.
  561.  
  562. Example:
  563.  
  564. PADLINES ON      ;Will turn on padding of blank lines
  565. PADLINES OFF     ;Will turn off padding of blank lines
  566.  
  567. ----------------------------------------------------------------------
  568.  
  569.         PALETTE
  570. Will open the palette requester.
  571.  
  572. ----------------------------------------------------------------------
  573.  
  574.         PRINTER
  575. Turns the printer ON or OFF.
  576.  
  577. Example:
  578.  
  579. PRINTER ON      ;Will turn on the printer
  580. PRINTER OFF     ;Will turn off the printer
  581.  
  582. ----------------------------------------------------------------------
  583.  
  584.         QUIT
  585. Exits NComm.
  586.  
  587. ----------------------------------------------------------------------
  588.  
  589.     READVAR
  590. This command reads a line from the file defined by VARFILE and places
  591. the input in the variable name that follows. Please refer to VARFILE.
  592.  
  593. The variable will contain "EOF" after the read if the function hits an
  594. end of file mark...
  595.  
  596. ----------------------------------------------------------------------
  597.  
  598.         REDIAL
  599. Turns redial ON or OFF.
  600.  
  601. Example:
  602.  
  603. REDIAL ON      ;Will turn redial on
  604. REDIAL OFF     ;Will turn redial off
  605.  
  606. ----------------------------------------------------------------------
  607.  
  608.         REPEAT<->UNTIL <expression> ...
  609. This  command  performs what is situated between REPEAT and UNTIL.  If
  610. the  expression  is  FALSE/TRUE,  the procedure will be repeated.  See
  611. "IF...THEN" for a discussion of valid expressions. The command has the
  612. same restrictions as WHILE/ENDWHILE.
  613.  
  614. Example:
  615.  
  616. REPEAT
  617.         SEND "Enter command: "
  618.         INPUT $cmd "\r"
  619.         GOSUB DoCommand
  620. UNTIL $cmd == "quit"
  621.  
  622. Numeric example that counts from 1 to 100:
  623.  
  624. REPEAT
  625.     SET $sum = $sum+"1"#
  626.     MESSAGE "Number: "$sum"\n"
  627. UNTIL $sum == "100"
  628.  
  629. ----------------------------------------------------------------------
  630.  
  631.         REQUEST
  632. This  function  is  used  when  the  scriptfile  is  run without human
  633. presence.   It  will  then  be  unpreferable  that  AmigaDOS puts up a
  634. requester  if  problems  occur (disk full, read / write error etc.) By
  635. turning request OFF, this is disabled.  Note: NComm will automatically
  636. overwrite existing files if request has been turned off
  637.  
  638. Example:
  639.  
  640. REQUEST OFF     ;Turns requesters off
  641. REQUEST ON      ;Will turn the requesters back on again
  642.  
  643. ----------------------------------------------------------------------
  644.  
  645.         RESUME
  646. Turns Zmodem resume ON or OFF.
  647.  
  648. Example:
  649.  
  650. RESUME ON      ;Turns Zmodem resume on
  651. RESUME OFF     ;Turns Zmodem resume off
  652.  
  653. ----------------------------------------------------------------------
  654.  
  655.         RETURN
  656. Returns from a subroutine. See GOSUB.
  657.  
  658. ----------------------------------------------------------------------
  659.  
  660.         SEND
  661. Sends a string to the host machine. You may use all the conventions
  662. that are valid for macrokeys. Please refer to the NComm.doc
  663.  
  664. Examples:
  665.  
  666. SEND "\n"       ;Linefeed
  667. SEND "Read\n"   ;'Read' plus a CR
  668. SEND "\m1^z"    ;Macro #1 plus a 'Control-Z'
  669. SEND "\p\n"     ;The password stored in the phonebook plus a CR
  670.  
  671. ----------------------------------------------------------------------
  672.  
  673.         SET
  674. This  command  is  used  for assigning values to variables.  Variables
  675. have  name  in  the form $name where 'name' starts with a letter.  The
  676. value  must be of type string, either a literal (with quotation marks)
  677. or  another  variable.  A number is assigned to a variable by entering
  678. the number as a string.
  679.  
  680. Examples:
  681.  
  682.         SET $name = "Daniel"
  683.         SEND $name
  684.  
  685.         SET $filename = "RAM:foo"
  686.         CAPTURE $filename
  687.  
  688.         SET $UserName = $name
  689.  
  690.         SET $Number1 = "13"
  691.         SET $Number2 = "5"
  692.         SET $Sum = $Number1+$Number2# ; Set Sum = Number1 + Number2 (18)
  693.         SET $Sum = $Sum+"1"#          ; Set Sum = Sum + 1
  694.         MESSAGE $Sum"\n"          ; Output the result (19)
  695.  
  696. The last example needs a bit of explanation. NComm threats string and
  697. numeric variables exactly the same way. The only difference is when
  698. you want to do some sort of calculation.
  699.  
  700. To specify that this line should perform a calculation, place a '#'
  701. character after the arithmetic expression. You may add strings or
  702. string variables after the arithmetic expression if necessary:
  703.  
  704.     MESSAGE "1"+"1"#"\n" ; Outputs '2' plus a linefeed.
  705.  
  706. Numbers always have priority from left to right. The following
  707. result will therefore be (1+5)*2 == 12, not 1+(5*2) == 11:
  708.  
  709.    SET $var = "1"+"5"*"2"#
  710.    MESSAGE $var"\n"
  711.  
  712. Negative variables are also accepted:
  713.  
  714.    SET $sum ="-1"+"-3"#"\n" ; The result is -4
  715.  
  716. The following arithmetic types are supported:
  717.  
  718.    '+': Addition              '/': Division
  719.    '-': Subtraction           '%': Modulo
  720.    '*': Multiplication        '^': Power
  721.  
  722. Variables  can  be  used everywhere where strings are expected.  There
  723. are a few pre-defined variables available:
  724.  
  725.    $date contains the current date and time (READ ONLY).
  726.    $ncomm contains the current version number (READ ONLY).
  727.    $baud contains the current baud rate (Read/Write).
  728.    $length contains the current data length (Read/Write).
  729.    $parity contains the current parity (Read/Write).
  730.    $stopbits contains the current number of stopbits (Read/Write)
  731.    $charset contains the current character set (Read/Write).
  732.    $filereq opens up a filereq and returns the filename (READ ONLY).
  733.    $stringreq opens up a textreq and returns the string (READ ONLY).
  734.    $rand gives you a random number between 0 and 65535 (READ ONLY).
  735.    $boardname contains the current board name (READ ONLY).
  736.    $boardnum contains the current board phone number (READ ONLY).
  737.    $logtime contains the current logon time (READ ONLY).
  738.    $dldir contains the current download dir (READ ONLY).
  739.    $uldir contains the current upload dir (READ ONLY).
  740.  
  741. Example that generates a random number between 0 and 15:
  742.  
  743.     set $range = "15"    ;Generate a random number between 0 and 15
  744.                         ;Actual result will be placed in the $newrand variable
  745.     main:
  746.     gosub rand
  747.     message "Your lucky number is: "$newrand"\n"
  748.     end
  749.  
  750.     rand:        ;To generate a new random number, gosub to this routine
  751.     set $newrange = $range+"1"#
  752.         set $newrand = $rand*$newrange/"65536"#
  753.         return
  754.  
  755. It is also possible to concatenate several variables and/or literals;
  756.  
  757.         SEND $name"\n"
  758.         SET $directory = "NComm:files/"
  759.         INPUT $filename "\r"
  760.         UPLOAD $directory$filename
  761.  
  762.         SET $baud = "300" ;sets baud-rate to 300 baud
  763.         SEND $date"\n"    ;print current date and time
  764.  
  765.         SET $length = "7" ;7 data bits
  766.         SET $parity = "E" ;even parity
  767.         SET $charset = "IBN" ;set IBN character set
  768.  
  769.         SET $var1 = "10"
  770.         SET $var2 = "10"
  771.         SET $var3 = $var1+$var2/"4"# ; Set $Var3 = ((10 + 10) / 4) == 5
  772.         MESSAGE $var3+"5"#"\n"       ; Display with linefeed: $Var3 + 5 == 10
  773.  
  774. It is not valid referring to variables having no value assigned.
  775.  
  776. NOTE: You may use the pre-defined variable $FILEREQ for obtaining
  777. a filename.
  778.  
  779. Example:
  780.       SET $filename = $FILEREQ ;open filereq, put name in $filename
  781.       IF $filename != "" CONFIG $filename ;use the filename
  782.  
  783. Use the pre-defined variable $STRINGREQ if you want the user to
  784. type in a string.
  785.  
  786. Example:
  787.       SET $baud = $STRINGREQ ;set baud-rate to number entered by user
  788.  
  789. ----------------------------------------------------------------------
  790.  
  791.     SIMPLEREQ
  792. Use this command if you want to display text in a seperate requester.
  793.  
  794. Example: SIMPLEREQ "You selected: "$filename"\n"
  795.  
  796. ----------------------------------------------------------------------
  797.  
  798.     STRLEN
  799. This function returns the length of a string.
  800.  
  801. Example: SET $foobar = "foobar"
  802.          STRLEN $len $foobar
  803.          MESSAGE $len"\n"
  804.  
  805. This example will output 6. You may also specify the text directly
  806. like this: STRLEN $len "foobar"
  807.  
  808. ----------------------------------------------------------------------
  809.  
  810.     STRPART
  811. This function copies parts of a string, starting at a specific position,
  812. into another string.
  813.  
  814. Example:
  815.          SET $varin = "foobar"
  816.          STRPART $varout 3 2 $varin
  817.          MESSAGE $varout"\n"
  818.  
  819. This example will output the string "ba" (startpos 3, length 2).
  820.  
  821. ----------------------------------------------------------------------
  822.  
  823.         TIMEOUT
  824. This  command lets you configure how long NComm should wait in a WAIT,
  825. CONVERSE  or INPUT command.  Default timeout is 'forever', but this is
  826. not  preferable if the script is running without human assistance.  If
  827. the  host machine does not answer, it is reasonable to believe that it
  828. has  hung,  and a scriptfile should then automatically disconnect from
  829. the system.  The TIMEOUT command can be used in many ways.
  830.  
  831. Examples:
  832.  
  833. TIMEOUT 10
  834. Means  that  NComm shall wait a maximum of 10 seconds.  If no text has
  835. been  received  within  the  timelimit, NComm will go on with the next
  836. command.
  837.  
  838. TIMEOUT 10 SEND "\n"
  839. Specifies  that NComm is to wait a maximum of 10 seconds for each WAIT
  840. or  CONVERSE  command.   If  the  specified text has not been received
  841. within  10 seconds, NComm will send a linefeed to the host machine and
  842. will  continue  waiting  for  the  text.   NComm will continue sending
  843. linefeeds every 10th second until the host machine has answered.
  844.  
  845. TIMEOUT 0
  846. NComm is to go back to the default mode, i.e. wait forever.
  847.  
  848. Example of typical usage:
  849.  
  850. TIMEOUT 30 GOTO quit
  851. CONVERSE "Enter your name:" "Daniel Bloch\n"
  852. CONVERSE "Enter your password:" "gruff\n"
  853. CONVERSE "Command:" "GRAB\n"
  854. ...
  855. ...
  856. END
  857.  
  858. quit: MESSAGE "\n\nThe board has hung, call the SysOp!!!\n"
  859.       BEEP
  860.       HANGUP ;Hang up so that we won't get a shock when
  861.       END    ;the next phonebill arrives!
  862.  
  863. ----------------------------------------------------------------------
  864.  
  865.         UPLOAD
  866. Uploads  a  file to the host machine.  See the 'DOWNLOAD' function for
  867. the correct syntax.
  868.  
  869. ----------------------------------------------------------------------
  870.  
  871.     VARFILE
  872. This command opens a file for input. The file may later on be used
  873. for reading text into variables via the command READVAR.
  874.  
  875. Example:
  876.     VARFILE "ncomm:host/users/"$user ;open input file for reading
  877.         READVAR $passwd ;place first line of file in variable $passwd
  878.         READVAR $laston ;place second line of file in variable $laston
  879.         VARFILE CLOSE ;closes the input file
  880.  
  881.         MESSAGE "Hello "$user"! You were last on at "$laston"\n"
  882.  
  883. ----------------------------------------------------------------------
  884.  
  885.         WAIT
  886. Waits  for  a  special  text to be received.  Will wait forever if the
  887. TIMEOUT command has not been used.
  888.  
  889. Examples:
  890.  
  891. WAIT ""         ;Wait for 'anything'
  892. WAIT "\n"       ;Wait for a linefeed
  893. WAIT "Command:" ;Wait for 'Command:'
  894.  
  895. ----------------------------------------------------------------------
  896.  
  897.         WHILE <expression> DO ... ENDWHILE
  898. This  function  performs what is situated within DO and ENDWHILE until
  899. the expression is TRUE/FALSE.
  900.  
  901. Example:
  902.  
  903. SET $cmd = ""
  904. WHILE !$cmd == "quit" DO
  905.         SEND "Enter command: "
  906.         INPUT $cmd "\r"
  907.         GOSUB DoCommand
  908. ENDWHILE
  909.  
  910. Numeric example that counts from 1 to 100:
  911.  
  912. SET $sum="0"
  913.  
  914. WHILE !$sum == "100" DO
  915.     SET $sum = $sum+"1"#
  916.     MESSAGE "Number: "$sum"\n"
  917. ENDWHILE
  918.  
  919. It  is  not  valid  jumping out of a WHILE/ENDWHILE loop using GOTO or
  920. RETURN.   It  is  still  possible  to exit the loop using GOTO and the
  921. command   CLRSTACK.
  922.  
  923. ----------------------------------------------------------------------
  924.  
  925.         WHEN
  926. Defines what to do when a special text is received. The command is
  927. case sensitive.
  928.  
  929. Typical example:
  930.  
  931. WHEN "--more--" SEND " "
  932.  
  933. This  command  will  make  NComm  send  a  'blank'  line every time it
  934. receives the 'more' prompt from the host machine.  This is independent
  935. of  where  in the script  you reside.  It is possible to specify up to
  936. twenty such textstrings.
  937.  
  938. Example:
  939.  
  940. WHEN "--more--" SEND " "
  941. WHEN "NO CARRIER" END
  942. WHEN "Sysop is coming online!" GOSUB ShutUp
  943. WHEN "No more unread" GOTO Quit
  944.  
  945. Loop: CONVERSE "Command:" "\n"
  946.       GOTO loop
  947.  
  948. Quit: SEND "G;Y\n"
  949.       END
  950.  
  951. ShutUp: SEND "I'm not at home! You are chatting with a scriptfile!\n"
  952.         SEND "Send BIBI at the speed of light!!!\n\n"
  953.         RETURN
  954.  
  955. ----------------------------------------------------------------------
  956.  
  957.         WRITE
  958. This command writes a textstring to a file. If the file exists, the
  959. string will be appended to the file. Example:
  960.  
  961.         WRITE "NComm:host/log" "Logged in: "$username"\n"
  962.               |                |
  963.               Name of file     String
  964.  
  965. ----------------------------------------------------------------------
  966.